== OnTime Rewards ==
With this component of the// OnTime// plugin the server administrator can establish a system of rewards, which will be automatically given to players when they reach specified lengths of time on your server.  The reward 'levels' are defined for number of days, hours, and minutes for one of four types of rewards: a economy amount to be put into the player's account; a quantity of an MC item to be added to a player's inventory; a change to a specified 'group' defined via a permissions plugin; a permission to be added to the player's permission list; or a command to be executed.
\\
\\
When a player logs into the system the next //OnTime Reward// for which the player is eligible will be determined, and a system event will be scheduled to issue that reward at the right time.  If a player quits or is kicked before their next reward time is reached, the reward event will be automatically cancelled.
\\
\\
===Economy Rewards Notes===
The //OnTime// plugin uses the [[http://dev.bukkit.org/server-mods/vault/|Vault ]] economy plugin, so any economy systems compatible with [[http://dev.bukkit.org/server-mods/vault/|Vault]] are therefore supported by //OnTime//. An econ reward can be further defined to be recurring, such the same reward is issued at each recurring time period.  
\\
\\
===Item Rewards Notes===
The item can be specified using the item NAME or item ID.  An item reward can also be further defined to be recurring, such the same reward is issued at each recurrenct time period.  
\\
\\
If at the time that an item reward is issued to a player the player's inventory is completely full, the user will be informed of the pending reward, and the plugin will try to issue the reward again in 1 minute.  The plugin will re-try every minute until the player makes room in their inventory to receive the reward.
\\
\\
===Group  & Permission Change Rewards Notes===
The //OnTime// plugin uses the [[http://dev.bukkit.org/server-mods/vault/|Vault ]] permissions plugin, so any permission systems compatible with [[http://dev.bukkit.org/server-mods/vault/|Vault]] are therefore supported by //OnTime//. A Vault supported permission plugin is required for this //OnTime// function to be available. 
\\
\\
Group and Permission rewards are one time events, so these cannot be defied as recurring.
\\
\\
Because there are countless permissions out there, no validity checking is done on the string entered.  So any incorrect permission specifications will not be detected by OnTime.  You will also never see any error messages from an incorrect permission spelling, so be careful.
\\
\\
For this Group Reward to work, the names of the different groups used by the system must be included in the //rewards.yml// file found in the '/plugins/ontime' directory.  It is very important that the groups be **listed in order from lowest to highest**.  The reason for this is that a player should never be automatically changed to a group which is lower than their currently assigned group.  This logic should help maintain group assignments made prior to adding OnTime to your plugin list.  The only way to add the groups to the //rewards.yml// is by editing the file directly and restarting the server.
\\
\\
For servers that have been running an V1.x version of the OnTime plugin, this version will automatically 'catch up' any players with missed group change rewards based on their //total OnTime//.  This catch up will happen once 'group' rewards are defined and upon player's next login. 'Catch up' does not occur for econ or item rewards.
\\
\\
Now that OnTime is taking better advantage of the Vault Permissions plugin, it will now keep in sync with any group changes, so the '/ontime refresh' command has been removed, and so has the need to specify the path to the permissions plugin in the config.yml file.
\\
\\
**OnTime will still function if permissions plugin is not installed.**
\\
\\
===Command Rewards Notes===
'Reward' may not be the right term since a command could be almost anything, but I'll call 'em rewards to be consistent.  For command rewards to be available they must first be defined in the rewards.yml file under the "commands:" keyword.  The format for these definitions is:
\\
\\
**- <commandTag>:'<command> <parameter> [player] <parameter>'**
\\
\\
><commandTag> is a string identifier you create for the command.  This is the string used in the '/ontime rewards add' command to define a reward of this type.
\\
><command> is the command you want to execute.  This can be almost* any command supported by your server.
\\
><parameter> is any parameters required by the command you want to be executed
\\
>'[player]' will be replaced with the target player's when the command is executed.
\\
//I say 'almost' because if there are more variables needed other than '[player]' it may not be possible to create a working reward for some commands.//
\\
====Examples====
\\
- xp100: 'xp [player] 100'
\\
- xp500: 'xp [player] 500'
\\
- kill: 'kill [player]'  (Ok, not really a good reward. :-) )
\\
\\
**Please note that the (') are required and that there must be no space before or after these marks.**
\\
\\
Unlike the rest of the rewards there is no in game notice sent to the player when the command happens.  I figure that the command itself will already have appropriate messages.
\\
\\

==Other Notes==
When //OnTime// is first installed there are no default rewards established, and there is no limit to the number of levels that can be defined.  Please see the [[http://dev.bukkit.org/server-mods/ontime/pages/commands/|Command page]] for details on how to set up the system.  The rewards can also be managed by direct editing of the// rewards.yml// file found in the// /plugin/ontime// folder.  Please see the //rewards.yml// page for more information.
\\
\\
Econ, Item and command rewards can be defined as recurring.  When one is so defined, the reward will be issued at every recurrence time period, until the player reaches the time of the next defined reward.  If the last reward defined is a recurring reward, that reward will be issued at every recurrence time period forever.
\\
\\
Example: A recurring reward of $100 is defined to start at 1 day 0 hour 0 min with a recurrence time of 0 days 4 hours 0 minutes,  and a second reward of $200 is defined to happen once at 2 days 0 hours 0 min.  Once the player has been on for 1 day they will receive a $100 reward every 4 hours until they have been on the server for 2 days, at which time they will received a $200 reward.  If there are no other rewards defined after this second one, the player would never receive another reward. 
\\
\\
Each time a reward is added or removed in game, the rewards for all online players are automatically recalculated to take into account the changes.
\\
\\
It is possible to control what players are eligible to receive the OnTime Rewards via permissions, so this capability can be reserved for certain classes or groups already established on the server.  See the [[http://dev.bukkit.org/server-mods/ontime/pages/permissions/|permissions]] page for more information.